get-tsconfig

What is get-tsconfig?

The get-tsconfig npm package is a utility for finding and reading TypeScript configuration files (tsconfig.json). It simplifies the process of locating the tsconfig.json file and parsing its contents, making it easier to work with TypeScript configurations programmatically.

What are get-tsconfig's main functionalities?

Find the tsconfig.json file

This feature allows you to locate the tsconfig.json file in your project. The `find` function searches for the tsconfig.json file starting from the current directory and moving up the directory tree until it finds one.

const { find } = require('get-tsconfig');
const tsconfigPath = find();
console.log(tsconfigPath);

Read and parse the tsconfig.json file

This feature allows you to read and parse the contents of the tsconfig.json file. The `load` function returns the parsed JSON content of the tsconfig.json file, making it easy to access and manipulate the TypeScript configuration programmatically.

const { load } = require('get-tsconfig');
const tsconfig = load();
console.log(tsconfig);

Specify a custom path to the tsconfig.json file

This feature allows you to specify a custom path to the tsconfig.json file. The `load` function can take a file path as an argument, enabling you to load and parse a tsconfig.json file from a specific location.

const { load } = require('get-tsconfig');
const tsconfig = load('/path/to/your/tsconfig.json');
console.log(tsconfig);

Other packages similar to get-tsconfig

tsconfig-paths

The tsconfig-paths package helps resolve TypeScript paths in Node.js. It reads the paths and baseUrl options from the tsconfig.json file and configures the module resolution accordingly. Unlike get-tsconfig, which focuses on finding and reading the tsconfig.json file, tsconfig-paths is more about resolving module paths based on the TypeScript configuration.

typescript

The typescript package itself provides the TypeScript compiler and related tools, including the ability to read and parse tsconfig.json files. While it offers more comprehensive functionality for working with TypeScript, it is more complex and heavier compared to the lightweight and focused get-tsconfig package.

cosmiconfig

The cosmiconfig package is a universal configuration loader that supports various configuration file formats, including JSON, YAML, and more. It can be used to find and load configuration files like tsconfig.json, but it is more general-purpose and not specifically tailored for TypeScript configurations like get-tsconfig.

README

^get-tsconfig

Find and parse tsconfig.json files.

Features

• Zero dependency (not even TypeScript)
• Tested against TypeScript for correctness
• Supports comments & dangling commas in tsconfig.json
• Resolves extends
• Fully typed tsconfig.json
• Validates and throws parsing errors
• Tiny! 7 kB Minified + Gzipped

^{Already a sponsor? Join the discussion in the Development repo!}

Install

npm install get-tsconfig

Why?

For TypeScript related tooling to correctly parse tsconfig.json file without depending on TypeScript.

API

getTsconfig(searchPath?, configName?, cache?)

Searches for a tsconfig.json file and parses it. Returns null if a config file cannot be found, or an object containing the path and parsed TSConfig object if found.

Returns:

type TsconfigResult = {

    /**
     * The path to the tsconfig.json file
     */
    path: string

    /**
     * The resolved tsconfig.json file
     */
    config: TsConfigJsonResolved
}

searchPath

Type: string

Default: process.cwd()

Accepts a path to a file or directory to search up for a tsconfig.json file.

configName

Type: string

Default: tsconfig.json

The file name of the TypeScript config file.

cache

Type: Map<string, any>

Default: new Map()

Optional cache for fs operations.

Example

import { getTsconfig } from 'get-tsconfig'

// Searches for tsconfig.json starting in the current directory
console.log(getTsconfig())

// Find tsconfig.json from a TypeScript file path
console.log(getTsconfig('./path/to/index.ts'))

// Find tsconfig.json from a directory file path
console.log(getTsconfig('./path/to/directory'))

// Explicitly pass in tsconfig.json path
console.log(getTsconfig('./path/to/tsconfig.json'))

// Search for jsconfig.json - https://code.visualstudio.com/docs/languages/jsconfig
console.log(getTsconfig('.', 'jsconfig.json'))

---

parseTsconfig(tsconfigPath, cache?)

The tsconfig.json parser used internally by getTsconfig. Returns the parsed tsconfig as TsConfigJsonResolved.

tsconfigPath

Type: string

Required path to the tsconfig file.

cache

Type: Map<string, any>

Default: new Map()

Optional cache for fs operations.

Example

import { parseTsconfig } from 'get-tsconfig'

// Must pass in a path to an existing tsconfig.json file
console.log(parseTsconfig('./path/to/tsconfig.custom.json'))

createFileMatcher(tsconfig: TsconfigResult, caseSensitivePaths?: boolean)

Given a tsconfig.json file, it returns a file-matcher function that determines whether it should apply to a file path.

type FileMatcher = (filePath: string) => TsconfigResult['config'] | undefined

tsconfig

Type: TsconfigResult

Pass in the return value from getTsconfig, or a TsconfigResult object.

caseSensitivePaths

Type: boolean

By default, it uses is-fs-case-sensitive to detect whether the file-system is case-sensitive.

Pass in true to make it case-sensitive.

Example

For example, if it's called with a tsconfig.json file that has include/exclude/files defined, the file-matcher will return the config for files that match include/files, and return undefined for files that don't match or match exclude.

const tsconfig = getTsconfig()
const fileMatcher = tsconfig && createFileMatcher(tsconfig)

/*
 * Returns tsconfig.json if it matches the file,
 * undefined if not
 */
const configForFile = fileMatcher?.('/path/to/file.ts')
const distCode = compileTypescript({
    code: sourceCode,
    tsconfig: configForFile
})

---

createPathsMatcher(tsconfig: TsconfigResult)

Given a tsconfig with compilerOptions.paths defined, it returns a matcher function.

The matcher function accepts an import specifier (the path to resolve), checks it against compilerOptions.paths, and returns an array of possible paths to check:

function pathsMatcher(specifier: string): string[]

This function only returns possible paths and doesn't actually do any resolution. This helps increase compatibility wtih file/build systems which usually have their own resolvers.

Example

import { getTsconfig, createPathsMatcher } from 'get-tsconfig'

const tsconfig = getTsconfig()
const pathsMatcher = createPathsMatcher(tsconfig)

const exampleResolver = (request: string) => {
    if (pathsMatcher) {
        const tryPaths = pathsMatcher(request)

        // Check if paths in `tryPaths` exist
    }
}

FAQ

How can I use TypeScript to parse tsconfig.json?

This package is a re-implementation of TypeScript's tsconfig.json parser.

However, if you already have TypeScript as a dependency, you can simply use it's API:

import {
    sys as tsSys,
    findConfigFile,
    readConfigFile,
    parseJsonConfigFileContent
} from 'typescript'

// Find tsconfig.json file
const tsconfigPath = findConfigFile(process.cwd(), tsSys.fileExists, 'tsconfig.json')

// Read tsconfig.json file
const tsconfigFile = readConfigFile(tsconfigPath, tsSys.readFile)

// Resolve extends
const parsedTsconfig = parseJsonConfigFileContent(
    tsconfigFile.config,
    tsSys,
    path.dirname(tsconfigPath)
)

Sponsors